package org.study.minio.boot.service;

import com.qcloud.cos.model.*;

import java.util.List;
import java.util.Map;

/**
 * 腾讯云 COS 对象存储服务接口
 * 官方文档：https://cloud.tencent.com/document/product/436/10199
 *
 * @author doveylovey
 * @version v1.0.0
 * @email 1135782208@qq.com
 * @date 2024年05月18日
 */
public interface CosService {
    /**
     * 查看指定名称的存储桶是否存在
     *
     * @param bucketName 存储桶名称，格式：BucketName-APPID
     * @return java.lang.Boolean
     */
    Boolean doesBucketExist(String bucketName);

    /**
     * 创建存储桶
     *
     * @param bucketName 存储桶名称，格式：BucketName-APPID
     * @param bucketName
     * @return com.qcloud.cos.model.Bucket
     */
    Bucket createBucket(String bucketName);

    /**
     * 查询用户的存储桶列表
     *
     * @return java.util.List<com.qcloud.cos.model.Bucket>
     */
    List<Bucket> listBuckets();

    /**
     * 上传对象：将本地文件或者已知长度的输入流内容上传到 COS，适用于20M以下图片类小文件上传，最大支持上传不超过5GB文件。5GB以上的文件必须使用分块上传或高级 API 接口上传
     *
     * @param bucketName    指定文件将要存放的存储桶
     * @param key           指定文件上传到 COS 上的路径，即对象键。例如对象键为 folder/picture.jpg，则表示将文件 picture.jpg 上传到 folder 路径下
     * @param localFilePath 指定要上传的文件
     * @return com.qcloud.cos.model.PutObjectResult
     */
    PutObjectResult upload(String bucketName, String key, String localFilePath);

    /**
     * 查询存储桶中对象列表
     *
     * @param bucketName 设置 bucket名称。Bucket 的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
     * @param prefix     表示列出的object的key以prefix开始
     * @return com.qcloud.cos.model.ObjectListing
     */
    ObjectListing listObjects(String bucketName, String prefix);

    /**
     * 获取对象的 CRC64
     * 参考 https://cloud.tencent.com/document/product/436/40334#java-sdk
     *
     * @param bucketName Bucket 的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
     * @param key        指定文件在 COS 上的路径，即对象键。例如对象键为 folder/picture.jpg，则表示下载的文件 picture.jpg 在 folder 路径下
     * @return java.lang.String
     */
    String getCRC64(String bucketName, String key);

    /**
     * 获取对象的输入流
     *
     * @param bucketName Bucket 的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
     * @param key        指定文件在 COS 上的路径，即对象键。例如对象键为 folder/picture.jpg，则表示下载的文件 picture.jpg 在 folder 路径下
     * @return byte[]
     */
    byte[] getObjectBytes(String bucketName, String key);

    /**
     * 下载对象：下载文件到本地的路径(如 D 盘的某个目录)
     *
     * @param bucketName     Bucket 的命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
     * @param key            指定文件在 COS 上的路径，即对象键。例如对象键为 folder/picture.jpg，则表示下载的文件 picture.jpg 在 folder 路径下
     * @param outputFilePath 下载文件到本地的路径，例如 D 盘的某个目录
     * @return Map<String, Object>
     */
    Map<String, String> downloadToLocal(String bucketName, String key, String outputFilePath);

    /**
     * 方法作用
     *
     * @param bucketName Bucket的命名格式为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
     * @param key        指定被删除的文件在 COS 上的路径，即对象键。例如对象键为 folder/picture.jpg，则表示删除位于 folder 路径下的文件 picture.jpg
     */
    void deleteObject(String bucketName, String key);

    /**
     * 方法作用
     *
     * @param bucketName Bucket的命名格式为 BucketName-APPID ，此处填写的存储桶名称必须为此格式
     * @param keys       要删除的文件名
     * @return java.util.List<java.lang.String>
     */
    List<String> deleteObjects(String bucketName, List<String> keys);
}
